Repository navigation
Complete configured Volume transfers through the native backend - #613
aakash-saravanan-db wants to merge 26 commits into
Conversation
|
Thanks for your contribution! To satisfy the DCO policy in our contributing guide every commit message must include a sign-off message. One or more of your commits is missing this message. You can reword previous commit messages with an interactive rebase ( |
ad49367 to
7b276d7
Compare
7b276d7 to
12876fc
Compare
There was a problem hiding this comment.
Verdict: 1 Medium · 1 Low
Mostly sound, with one medium issue: on the kernel path, the new StagingError wrapping can also catch the statement's own execution errors, not just transfer errors. Nits: there is a stray blank line in the CHANGELOG entry, and the constructor comment in KernelOperationBackend still says cancel() "always routes to the cancellable execution". Follow-up (not caused by this PR): executeStatement waits for the transfer before it returns the operation, so a caller can only interrupt an in-flight transfer by closing the session.
| expect(executionCancelled).to.equal(false); | ||
| }); | ||
|
|
||
| for (const outcome of ['completed', 'not_volume']) { |
There was a problem hiding this comment.
🔵 Low — The new tests cover only the completed and not_volume outcomes and the cancel routing. These new branches in completeStagingOperation have no unit test:
- the
needs_input_stream→StagingErrorpath - reclassifying
ParameterErrorandhttpStatuserrors asStagingError - passing other errors through unchanged (for example local fs errors decoded with
code/path)
No test checks that DBSQLSession closes the operation when completion fails either. The error-classification branch is where F1 lives, so a test there would have caught it.
There was a problem hiding this comment.
Verdict: 1 Low
Looks good overall, with one low-severity concern. If the native layer returns a completion outcome this code doesn't recognise, the call succeeds with no transfer and no error. Two nits: CHANGELOG.md has a stray blank line in the middle of the bullet list, and when a ParameterError or storage error is turned into a StagingError, the kernel metadata (httpStatus/errorCode) and the cause are lost. That matches Thrift's StagingError, but it's worth noting.
| if (outcome === 'needs_input_stream') { | ||
| throw new StagingError('Volume PUT requires a local file path'); | ||
| } | ||
| this.volumeCompleted = outcome === 'completed'; |
There was a problem hiding this comment.
🔵 Low — The native binding returns completeVolumeOperation outcomes as a bare string. This code handles 'needs_input_stream' and 'completed'. Every other value, including one a future kernel adds or one that is misspelled, gets the same treatment as 'not_volume': executeStatement resolves without an error and the caller gets the raw instruction rows. The user configured stagingAllowedLocalPath, so a transfer can silently not happen. A failure-loud check would fix this: accept only 'completed' and 'not_volume', and throw a StagingError such as Unexpected Volume completion outcome: ${outcome} for anything else.
There was a problem hiding this comment.
The compatible pinned NAPI producer maps the closed VolumeCompletion enum directly through as_str: its only outputs are not_volume, needs_input_stream and completed (src/volume.rs, napi/src/statement.rs, napi/src/async_statement.rs). This adapter handles all three, so no current native path produces the proposed unexpected value. A defensive check for a future or mismatched binding remains optional; compatible platform package pins/locks and clean installation are still required before merge.
The review-body nits remain acknowledged: preserving cause/extra metadata could improve StagingError diagnostics, while the current shape follows the audited Thrift error; the changelog blank line is cosmetic.
There was a problem hiding this comment.
Agreed that the pinned NAPI producer emits only not_volume, needs_input_stream and completed, and that all three are handled today. The concern was about a mismatched or future binding. Line 322 still treats any unrecognized string as not_volume and resolves without an error, and nothing in this package enforces the native enum, since the binding is typed as string and the platform packages are versioned separately. Throwing a StagingError when the outcome isn't completed or not_volume costs two lines and turns a silent skipped transfer into a visible error. It's still Low and optional, so I'm leaving the thread open for the maintainers to decide.
Signed-off-by: Aakash Saravanan <aakash.saravanan@databricks.com>
There was a problem hiding this comment.
Verdict: 1 Medium · 1 Low
Mostly sound, with one medium blocker: Volume completion calls a native API that the pinned native 1.4.0 binding doesn't have. As a result, every kernel statement that sets stagingAllowedLocalPath, including a plain SELECT, now fails with a TypeError. Before this change the option was logged and ignored. Nit: the constructor comment saying cancel() "always routes to the cancellable execution" is out of date now that cancel() goes to the resolved statement.
| failIfNotActive(this.lifecycle); | ||
| const handle = await this.getFetchHandle(); | ||
| try { | ||
| const outcome = await handle.completeVolumeOperation(allowedPaths, true); |
There was a problem hiding this comment.
🟡 Medium — completeStagingOperation calls handle.completeVolumeOperation(...) without checking that the loaded binding has it. The optional dependencies are still pinned to native 1.4.0, which has no completion API, so on the kernel backend every executeStatement with stagingAllowedLocalPath now fails, including a plain SELECT. The error is TypeError: handle.completeVolumeOperation is not a function. decodeNapiKernelError passes it through unchanged, and the facade closes the operation.
Before this PR the option was logged and ignored, so callers that set it globally and run ordinary queries break.
The facade check if (opBackend.completeStagingOperation) doesn't prevent this. That method exists on every KernelOperationBackend instance, so the check is always true. The check needs to be on the native handle. If typeof handle.completeVolumeOperation !== 'function', either keep the earlier behaviour (do nothing and return the raw instruction rows) or throw a clear HiveDriverError that names the minimum native version. Alternatively, bump the dependency pins in this PR.
There was a problem hiding this comment.
Published native 1.4.0 is incompatible. The actual compatible versions, all eight platform dependency pins/locks, and clean installed ordinary-query/metadata/Volume proof remain required before merge; a source SHA pin does not satisfy those requirements. This is a coordinated-release dependency, with no older-native fallback in the selected contract. A stale-binding method check could improve the load/runtime diagnostic, but cannot make the missing API compatible or replace the package gate. The PR remains blocked on that gate.
There was a problem hiding this comment.
Agreed, a method check on the handle can't make native 1.4.0 compatible, and bumping the pins is the real fix. That's still outstanding, though: line 318 calls handle.completeVolumeOperation with no guard, and the optional dependencies still point to 1.4.0. I'm leaving this thread open until the new versions are published and all eight platform pins and locks are bumped. That way it stays in the unresolved queue as the visible merge gate. If the release slips and this branch gets installed against 1.4.0, a typeof guard that throws a HiveDriverError naming the minimum native version would still be cheap. It would replace an unclear TypeError on a plain SELECT.
| (mapped instanceof ParameterError && !metadata?.httpStatus) || | ||
| metadata?.errorCode === 'VOLUME_STORAGE_HTTP_ERROR' | ||
| ) { | ||
| throw new StagingError(mapped.message); |
There was a problem hiding this comment.
🔵 Low — When a policy or storage-HTTP failure is re-thrown as new StagingError(mapped.message), the decoded error's kernelMetadata, including httpStatus, errorCode (VOLUME_STORAGE_HTTP_ERROR) and queryId, is thrown away, along with its sqlState and cause. Callers then can't tell a storage 403 from a 404 or correlate the failure with a query, even though the PR keeps this metadata on the other error paths. Copying kernelMetadata and cause onto the StagingError (for example with Object.assign or Object.defineProperty, matching how KernelErrorMapping attaches them) keeps the established error class and the diagnostics.
There was a problem hiding this comment.
Additional metadata/cause on StagingError would improve diagnostics. The current mapping deliberately retains the established Thrift staging error class/shape, while SQL instruction errors keep their decoded metadata. Native storage HTTP failures retain their specific Volume storage request failed: HTTP ... diagnostic, so the storage-origin deletion check does not depend on discarded metadata or accept a generic statement 404. This remains an acknowledged optional diagnostic enhancement.
The review-body constructor comment is also a valid optional wording improvement: cancellation uses the cancellable execution while pending and the resolved statement afterward. Existing cancellation/lifetime behavior is preserved.
There was a problem hiding this comment.
Understood that keeping the established StagingError class is deliberate, and I'm fine with that part. My suggestion was never to change the class, only to attach the diagnostics to it. The code at line 330 still builds a new StagingError from the message alone. The HTTP ... text in the message helps a human reading it, but queryId, errorCode, sqlState and cause are still lost, so callers have nothing structured to branch on or use for correlation. This is Low severity and fine to defer. I'm leaving the thread open so the follow-up stays visible: one Object.defineProperty for kernelMetadata/cause on the new error would fix it without changing its class or shape.
Signed-off-by: Aakash Saravanan <aakash.saravanan@databricks.com>
There was a problem hiding this comment.
Verdict: 2 Low · 1 Nit
Mostly sound, with three low-severity robustness gaps: no check that the native completion API exists, unknown completion outcomes treated as success, and unchecked OS error numbers. Nits: CHANGELOG.md adds a stray blank line inside the bullet list, and the new error-mapping tests sit at the top level instead of inside a describe block. Follow-up (dependency, not a defect in this diff): releasing still needs native pins that include completeVolumeOperation, and forcing sync execution whenever stagingAllowedLocalPath is set also applies to long non-Volume statements.
Other findings
- ⚪ Nit — Every outcome other than
'completed'and'needs_input_stream'is treated the same as'not_volume': no error, and the raw instruction rows stay visible. If the kernel adds an outcome later, or returns an unexpected string, the caller gets no file effect and no error even though they configuredstagingAllowedLocalPath. Consider treating only'not_volume'as the pass-through case and throwing aStagingErrorfor any other unrecognised value.
| failIfNotActive(this.lifecycle); | ||
| const handle = await this.getFetchHandle(); | ||
| try { | ||
| const outcome = await handle.completeVolumeOperation(allowedPaths, true); |
There was a problem hiding this comment.
🔵 Low — completeVolumeOperation is called without checking that it exists. The PR says published native 1.4.0 lacks the completion APIs, and the backend's own statement type is Partial<KernelStatement>. On a binding without the method, every kernel executeStatement that sets stagingAllowedLocalPath fails with TypeError: handle.completeVolumeOperation is not a function, and DBSQLSession then closes the operation. That includes ordinary SELECT/DML statements that aren't Volume operations; before this PR they ran with a warning. A typeof handle.completeVolumeOperation !== 'function' guard would fix it. It could throw a clear HiveDriverError/StagingError saying the native binding is too old, or fall back to the previous behaviour for non-volume statements (isVolumeOperation falsy).
There was a problem hiding this comment.
The incompatible-package concern is valid and remains a required merge gate: compatible native platform versions, all dependency pins/locks, and clean installed SELECT/metadata/Volume proof. Native 1.4.0 lacks these APIs. The source build selects kernel30c8d8e7; both the rebuilt sync/async lifecycle comparisons and ordinary-query controls pass. Coordinated native uptake is required, so we are retaining direct calls rather than adding an older-native compatibility path. This PR is not ready to merge until that release gate passes.
There was a problem hiding this comment.
Thanks for confirming. Requiring a coordinated native release instead of adding a compatibility path is a reasonable choice. The code at this line still calls completeVolumeOperation directly, though. Until the published native dependency is pinned to a version that has the completion APIs, an install that pulls native 1.4.0 will still fail ordinary statements that set stagingAllowedLocalPath. I'll leave this thread open so the release gate stays in the unresolved queue. It can be closed once the pin and lockfile point to a compatible native release, or once a guard is added.
Signed-off-by: Aakash Saravanan <aakash.saravanan@databricks.com>
|
Disposition of the remaining optional review suggestions: the pinned native completion result has the three declared outcomes, and native errors reject; an added outcome requires a coordinated binding/type update. No unexpected-outcome path is reachable with the selected native, so an additional future-outcome guard remains optional. The existing table tests have unique case names and assertions; wrapping them or changing the changelog spacing would add no behavior coverage. The configured-path execution choice preserves the existing staging contract. Compatible released platform packages, pins/locks, clean installs and named scheduled execution remain open gates. |
There was a problem hiding this comment.
Verdict: 2 Low
Looks good overall, with 2 low findings: error metadata is dropped when failures are re-wrapped as StagingError, and the needs_input_stream outcome has no test. The wiring between DBSQLSession, the kernel backend and native completion is consistent, and cleanup on failure is correct. One nit: the CHANGELOG entry is followed by a stray blank line that splits the bullet list.
| (mapped instanceof ParameterError && !metadata?.httpStatus) || | ||
| metadata?.errorCode === 'VOLUME_STORAGE_HTTP_ERROR' | ||
| ) { | ||
| throw new StagingError(mapped.message); |
There was a problem hiding this comment.
🔵 Low — When a transfer failure is re-wrapped as new StagingError(mapped.message), the error loses kernelMetadata (including queryId and httpStatus/errorCode) and the non-enumerable cause that decodeNapiKernelError attaches. Other paths now keep these fields; the PR description says deferred instruction errors keep their metadata, and the tests check that too. For storage HTTP failures (VOLUME_STORAGE_HTTP_ERROR), callers can no longer see the HTTP status or the query id needed to match the failure in server logs. Consider copying kernelMetadata and cause onto the StagingError, for example with Object.defineProperty as the mapper already does. This keeps the error class callers expect and still preserves the diagnostics.
There was a problem hiding this comment.
The diagnostic loss is real and remains the previously acknowledged optional enhancement. Keeping kernelMetadata/cause would improve storage-error correlation without changing the StagingError class. The current class/message follows the audited Thrift staging contract; deferred SQL instruction failures retain their decoded metadata. The specific storage diagnostic is retained, and the strict deletion oracle rejects generic statement/instruction 404s without relying on dropped metadata. This finding remains visible; no required baseline behavior or newly demonstrated failure calls for another adapter change.
There was a problem hiding this comment.
Thanks for confirming the diagnostic loss is real. Keeping the StagingError class and message for the Thrift staging contract makes sense, and the fix I suggested doesn't change that. It only adds the non-enumerable kernelMetadata/cause properties to the same error. The code at line 329 still drops them, so storage HTTP failures can't be matched to server logs by queryId or httpStatus. This is Low severity and isn't blocking. I'm leaving the thread open so the optional fix stays in the queue for someone to pick up later.
| failIfNotActive(this.lifecycle); | ||
| const handle = await this.getFetchHandle(); | ||
| try { | ||
| const outcome = await handle.completeVolumeOperation(allowedPaths, true); |
There was a problem hiding this comment.
🔵 Low — The needs_input_stream branch has no unit test. Its StagingError is thrown inside the try, so it also goes through decodeNapiKernelError and the classification logic, and no test confirms it comes out unchanged. Any other unrecognised outcome string from a future native version is also treated silently as 'not completed', and the raw instruction rows are returned. Add a test case for needs_input_stream. Also consider throwing or logging when the outcome is not one of the known values (completed / not_volume / needs_input_stream).
There was a problem hiding this comment.
The sentinel instruction can reach this branch; it is not unreachable. Node has no input-stream upload API, so needs_input_stream produces the explicit StagingError. decodeNapiKernelError returns that ordinary Error unchanged, and it cannot satisfy either remapping condition. No incorrect branch behavior is established. An additional test of this direct rejection remains optional; core handshake/owned-byte coverage and distinct Node storage/instruction/error/lifecycle coverage remain. Unknown future outcomes retain the earlier optional disposition; supported native inputs require coordinated platform pins/locks.
There was a problem hiding this comment.
You're right that this branch is reachable, and your explanation of why decodeNapiKernelError should pass the StagingError through unchanged makes sense. My concern was never that the branch behaves wrongly today. It was that nothing locks that behavior in. If someone later changes the catch classification, this rejection could get wrapped or remapped without any test failing, and a single mocked completeVolumeOperation returning 'needs_input_stream' would cover that cheaply. For unknown future outcome strings, coordinated platform pins lower the risk but don't remove it: a version mismatch would still silently report "not completed". I'm leaving this open at Low severity for a human to decide whether to add the test and an else throw or log. No code change is needed to keep the current behavior correct.
Signed-off-by: Aakash Saravanan <aakash.saravanan@databricks.com>
There was a problem hiding this comment.
Verdict: 1 Medium · 2 Low
Mostly sound, with 1 medium concern: there is no feature check on the native completion API while the published 1.4.0 binary that package.json still pins lacks it. Session dispatch, cleanup on failure, cancel routing and errno decoding look correct. Nit: the CHANGELOG entry adds a stray blank line inside the bullet list.
| failIfNotActive(this.lifecycle); | ||
| const handle = await this.getFetchHandle(); | ||
| try { | ||
| const outcome = await handle.completeVolumeOperation(allowedPaths, true); |
There was a problem hiding this comment.
🟡 Medium — handle.completeVolumeOperation(...) is called without checking that the loaded binding has it. The packages declared in package.json are still 1.4.0, and per the PR description that version has no completion API. With that binary installed, any kernel executeStatement that passes stagingAllowedLocalPath fails with TypeError: handle.completeVolumeOperation is not a function. That includes a plain SELECT. Before this change the option was logged and ignored. decodeNapiKernelError returns non-envelope errors unchanged, and DBSQLSession then closes the operation and rethrows, so callers see the raw TypeError.
The PR does say merge depends on updated pins. Until that happens, though, every environment that installs from npm gets this regression. Either guard with typeof handle.completeVolumeOperation === 'function' and throw a clear StagingError or HiveDriverError (or keep the old no-op), as readStatusFieldsFrom does for older bindings, or block the merge on the pin bump.
There was a problem hiding this comment.
Agreed: compatible native packages, all eight platform pins/locks and clean installed SELECT, metadata and Volume proof are required before this PR can merge. The declared 1.4.0 inputs do not satisfy the new API contract, and the source SHA pin is not released-package proof. This gate remains open in the PR description. Coordinated native uptake is required; an older-binding no-op/fallback would conceal unsupported Volume behavior and is not the selected contract. No merge-ready or complete-parity claim is made.
There was a problem hiding this comment.
Thanks, blocking the merge on the native package bump is one of the resolutions I suggested, and choosing it over a silent no-op makes sense. Line 317 still calls handle.completeVolumeOperation with no guard, though, and package.json still pins 1.4.0. So the regression is real at current head. I'll leave this thread open as the visible merge gate. It can be resolved once the eight platform pins and lockfile point at a released binding that ships the completion API.
| metadata?.errorCode === 'VOLUME_STORAGE_HTTP_ERROR' | ||
| ) { | ||
| throw new StagingError(mapped.message); | ||
| } |
There was a problem hiding this comment.
🔵 Low — When a transfer error is reclassified as StagingError, only message is kept. The decoded error's kernelMetadata (queryId, httpStatus, errorCode) and its non-enumerable cause are lost. A storage VOLUME_STORAGE_HTTP_ERROR then reaches the caller with no status code or query id to correlate, even though decodeNapiKernelError worked to attach them. Copying kernelMetadata and cause onto the new StagingError, for example with Object.defineProperty as the mapping module does, would keep the type change without losing diagnostics.
There was a problem hiding this comment.
The metadata/cause loss is real and remains the previously acknowledged optional diagnostic enhancement. The StagingError class and message follow the audited Thrift staging contract; SQL/instruction-side failures keep their decoded metadata. Genuine storage failures retain the specific storage diagnostic, and deletion verification rejects generic instruction/statement 404s without depending on discarded metadata. This repeats the earlier disposition; no new required behavior failure is established.
There was a problem hiding this comment.
Thanks. We agree on the facts: the loss of kernelMetadata and cause is real, and this is a Low-severity diagnostic issue, not a functional failure. Line 329 still builds new StagingError(mapped.message) with nothing else attached. So for a VOLUME_STORAGE_HTTP_ERROR, the caller never sees the httpStatus, queryId or errorCode that the decoder already extracted. Copying those fields onto the new error wouldn't change its class or message, so it wouldn't conflict with the Thrift staging contract. I'm leaving this open so a maintainer can decide whether to add the fields in this PR or track it separately.
| const handle = await this.getFetchHandle(); | ||
| try { | ||
| const outcome = await handle.completeVolumeOperation(allowedPaths, true); | ||
| if (outcome === 'needs_input_stream') { |
There was a problem hiding this comment.
🔵 Low — No unit test covers the 'needs_input_stream' outcome. That branch throws a StagingError inside the try, which is then decoded again and run through the reclassification check. The Volume completion tests only exercise 'completed', 'not_volume' and thrown errors. Please add a case asserting that 'needs_input_stream' rejects with StagingError('Volume PUT requires a local file path').
There was a problem hiding this comment.
The sentinel branch is reachable and intentionally rejects with StagingError('Volume PUT requires a local file path'). decodeNapiKernelError returns an ordinary non-envelope Error unchanged, and this StagingError satisfies neither remapping condition, so its class/message survive. This repeats the existing branch-test disposition. The extra mocked assertion remains optional; the distinct storage/instruction/error/lifecycle tests remain. No behavior defect is demonstrated.
There was a problem hiding this comment.
I agree with your reasoning about the runtime behaviour. decodeNapiKernelError passes a plain non-envelope Error through unchanged, and this StagingError matches neither remapping condition, so it should reach the caller as is. My finding wasn't about a bug, though. It was about the missing regression test, and there's still no test under tests/ that mentions needs_input_stream or the message "Volume PUT requires a local file path". That makes the class and message you've described an unenforced contract: if the catch block's decode or reclassification logic changes later, nothing will catch it. One mocked completeVolumeOperation returning 'needs_input_stream' would cover it. It's low priority, so I'll leave the thread open for you to decide whether to add it before merge.
Signed-off-by: Aakash Saravanan <aakash.saravanan@databricks.com>
There was a problem hiding this comment.
Verdict: 1 Low
Looks good overall, with one low concern: when transfer failures are turned into StagingError, the kernel's diagnostic metadata is dropped. Native dispatch, closing the operation on failure, consuming instruction rows, forcing inline execution, and decoding errno values all look correct, and unit tests cover them. Nit: the CHANGELOG adds a stray blank line inside the bullet list.
| (mapped instanceof ParameterError && !metadata?.httpStatus) || | ||
| metadata?.errorCode === 'VOLUME_STORAGE_HTTP_ERROR' | ||
| ) { | ||
| throw new StagingError(mapped.message); |
There was a problem hiding this comment.
🔵 Low — When a transfer failure is reclassified, new StagingError(mapped.message) keeps only the message. The decoded error's kernelMetadata is dropped, including httpStatus, errorCode: 'VOLUME_STORAGE_HTTP_ERROR' and queryId, and so is its non-enumerable cause. Every other kernel error keeps that metadata, and the PR description says HTTP errors and their metadata stay intact. A caller that hits a storage 403/404 therefore gets a StagingError whose status can only be recovered by parsing the message, and there's no query id to correlate with the server.
A contained fix is to copy kernelMetadata (and cause) from mapped onto the new StagingError before throwing it. The tests could then assert that kernelMetadata.httpStatus survives in the VOLUME_STORAGE_HTTP_ERROR case.
There was a problem hiding this comment.
This is the acknowledged optional storage-diagnostic enhancement. Storage failures retain the audited StagingError class and the specific storage diagnostic; deferred SQL instruction HTTP failures retain decoded metadata as stated in the description. The comparator’s REMOVE verification in databricks/databricks-driver-test#2122 requires storage-origin evidence and rejects generic instruction/statement 404s independently of these dropped properties. Copying kernelMetadata/cause would improve correlation, but no required Thrift behavior or newly demonstrated incorrect transfer/error outcome requires an adapter change.
There was a problem hiding this comment.
Thanks for clarifying. I accept that the PR description's metadata promise covers deferred SQL instruction HTTP failures rather than storage failures, and that the comparator in databricks-driver-test#2122 checks for storage-origin evidence without needing these properties. The code at line 329 still rebuilds the error from mapped.message alone, though, so a caller who catches the StagingError loses httpStatus, errorCode and queryId. The only way to recover the status is to parse the message, and there's no query id to correlate with the server. This stays Low and doesn't need to block the merge. I'll leave the thread open so a human can decide whether to copy kernelMetadata and cause over now or in a follow-up.
Signed-off-by: Aakash Saravanan <aakash.saravanan@databricks.com>
There was a problem hiding this comment.
Verdict: 3 Low
Mostly sound. Native completion is called only on kernel backends, failed completions close the operation, and errno decoding is defensive. I found three low-severity issues: the StagingError rewrap loses diagnostic metadata, unknown completion outcomes succeed without a transfer, and the PUT-without-local-path branch has no test. Nits: a stray blank line inside the CHANGELOG list after the new entry, and IOperationBackend.completeStagingOperation has no JSDoc describing its contract, unlike its neighbouring methods.
| (mapped instanceof ParameterError && !metadata?.httpStatus) || | ||
| metadata?.errorCode === 'VOLUME_STORAGE_HTTP_ERROR' | ||
| ) { | ||
| throw new StagingError(mapped.message); |
There was a problem hiding this comment.
🔵 Low — Converting a tagged storage HTTP error or a local-policy ParameterError into new StagingError(mapped.message) drops everything the decoder attached: kernelMetadata (including httpStatus, errorCode: 'VOLUME_STORAGE_HTTP_ERROR' and queryId) and the non-enumerable cause.
After the rewrap, a caller cannot tell a 403 from a 404 except by parsing the message, and cannot link the failure to its statement. The deferred instruction errors next to this path keep their metadata intact (the tests check this), so these two error kinds now behave differently.
Consider copying kernelMetadata and cause onto the new StagingError, for example with Object.assign or Object.defineProperty, so the error type changes but the diagnostics survive.
There was a problem hiding this comment.
This is the acknowledged optional storage-diagnostic enhancement. Storage failures retain the audited StagingError class and the specific storage diagnostic; deferred SQL instruction HTTP failures retain decoded metadata as stated in the description. The comparator’s REMOVE verification in databricks/databricks-driver-test#2122 requires storage-origin evidence and rejects generic instruction/statement 404s independently of these dropped properties. Copying kernelMetadata/cause would improve correlation, but no required Thrift behavior or newly demonstrated incorrect transfer/error outcome requires an adapter change.
There was a problem hiding this comment.
Understood, and I agree this is Low severity and doesn't change Thrift behavior or transfer outcomes. Your reply also confirms the diagnostics are lost: line 329 still builds a bare new StagingError(mapped.message), so httpStatus, errorCode and queryId are gone for storage failures but kept for deferred instruction failures. The comparator in databricks-driver-test#2122 can work without them, but driver callers outside that harness can't. This is a two-line change that keeps the StagingError class: Object.assign(err, { kernelMetadata: metadata }) and define cause on the new error. I'll leave the thread open so a maintainer can decide whether to take it now or track it as a follow-up.
| const handle = await this.getFetchHandle(); | ||
| try { | ||
| const outcome = await handle.completeVolumeOperation(allowedPaths, true); | ||
| if (outcome === 'needs_input_stream') { |
There was a problem hiding this comment.
🔵 Low — No test covers the 'needs_input_stream' branch. In particular, nothing checks that the StagingError thrown inside the try passes through decodeNapiKernelError and the reclassification logic unchanged. The Volume completion tests cover only 'completed' and 'not_volume'.
There is also no tests/e2e/ coverage of kernel Volume PUT/GET/REMOVE, even though the change has visible effects on files and storage. The PR description mentions out-of-tree comparisons only.
There was a problem hiding this comment.
The sentinel branch is reachable, and the plain StagingError is passed through by decodeNapiKernelError; it matches neither remapping condition in this catch. The additional mocked assertion remains optional, with no incorrect runtime outcome established. Distinct native owned-input, adapter error/cancellation/lifecycle and real-driver transfer groups remain.
The shared end-to-end workflows are in databricks/databricks-driver-test#2122, tests/comparator-tests/node/config/thrift-vs-sea.yaml. The retained source-built sync/async DBSQL comparisons at kernel029c59cc have two matches, 20 successful positive steps and zero differences, including initial/changed bytes and storage-origin removal. Compatible installed-native and named scheduled proof remain open; duplicating that shared journey in another connector matrix would not close either gate.
There was a problem hiding this comment.
Pointing to the shared comparator workflows in databricks-driver-test#2122 is a fair answer to the e2e half of this, and I'm not claiming the current code behaves incorrectly. The unit-test gap is still open, though. The 'needs_input_stream' branch is reachable, but no test exercises it. That means nothing would catch a future change to decodeNapiKernelError or to the reclassification conditions that starts remapping or wrapping this StagingError. A small mocked test would cover it: stub completeVolumeOperation to resolve 'needs_input_stream', then assert that a StagingError with this message is rejected and that volumeCompleted stays false. This is Low severity, so I'll leave it to the maintainers whether it blocks the PR.
Signed-off-by: Aakash Saravanan <aakash.saravanan@databricks.com>
There was a problem hiding this comment.
Verdict: 1 Medium
Mostly sound, with one medium concern: on the sync execution path, cancel() now goes to the lock-holding Statement, which can make it wait behind in-flight fetches and transfers. Follow-ups outside this diff: package.json still pins native 1.4.0, which lacks completeVolumeOperation, so any kernel-backend call with stagingAllowedLocalPath would throw a TypeError until the pins are bumped (the PR description already notes this). Nit: the new CHANGELOG entry adds a stray blank line that splits the bullet list and has no PR number.
Signed-off-by: Aakash Saravanan <aakash.saravanan@databricks.com>
There was a problem hiding this comment.
Verdict: 1 Low
Looks good overall, with one low-severity concern: cancelling a transfer on the direct-results Running path isn't routed or tested the way the composite path is. Nit: CHANGELOG.md has a stray blank line after the new Volume entry. Follow-up outside this PR: the native dependency pins and installed-package validation are still open, as the description says.
| ? { | ||
| cancel: () => cancellableExecution.cancel(), | ||
| cancel: () => | ||
| this.blockingStatement?.isVolumeOperation ? this.blockingStatement.cancel() : cancellableExecution.cancel(), |
There was a problem hiding this comment.
🔵 Low — The new cancel routing (cancel the resolved statement once a marked transfer is underway) only applies to the cancellableExecution composite. Configured staging now goes through executeStatementDirect (see the new execution test). That call returns either a terminal Statement or, when the query outlives the inline wait, an AsyncStatement. In the Running case, lifecycleHandle is the AsyncStatement, but completeVolumeOperation runs on the AsyncResultHandle returned by awaitResult(). So operation.cancel() during a long PUT/GET goes to asyncStatement.cancel(), and nothing in this PR shows that this interrupts the transfer. I couldn't check the native side, so this may be fine if the kernel links the two. Either way, the only cancel-routing tests use the cancellableExecution stub, so the path the default execution actually takes has no coverage. Please add a test, or route cancel to the result handle once isVolumeOperation is known, as the composite does.
There was a problem hiding this comment.
The pinned native links these handles through the same VolumeState Arc. ExecutedAsyncStatement::canceller clones self.volume; result materialization attaches Arc::clone(volume) to its ResultStream. NAPI AsyncStatement.cancel signals that state before awaiting remote SQL cancellation, independently of the result mutex. AsyncResultHandle has no cancel method, so routing to the parent is intentional. An independent control with the compiled adapter at 2163c91 and native built from d9fcf834 exercises executeStatementDirect returning Running, the real awaitResult, and completion on its marked result handle. With storage DELETE held, backend.cancel settled in 1 ms and completion returned CANCELED before storage release, with exactly one storage request. This deterministic shared-transfer control closes the linkage question; it is not a new warehouse PUT/GET comparison or installed-package proof. No additional adapter routing is needed.
There was a problem hiding this comment.
Thanks, the shared VolumeState Arc explanation answers my question about whether cancel interrupts the transfer. Routing cancel to the parent AsyncStatement is fine, since AsyncResultHandle has no cancel(). The control run you describe used a separate local build, though, and nothing in this PR records it. The unit tests for the direct path in operation-lifecycle.test.ts only cover close and status. None of them cancels during a marked transfer on the Running arm. Without that test, a later change to the adapter could break this routing and CI would still pass. A small stub test would close the gap: executeStatementDirect returns Running, awaitResult returns a marked result handle, and the test asserts that operation.cancel() calls asyncStatement.cancel() while completion is in progress. I'm leaving the thread open so someone can decide whether to add that test.
Feature or gap
Kernel-backed sessions need to complete server-marked Volume PUT, GET and REMOVE operations through the existing staging API.
What this PR addresses
Delegate authorized transfers to native completion and preserve raw instructions otherwise. Post-SQL cancellation uses the resolved statement for marked transfers and the execution handle for ordinary statements. Validate native errno values before OS lookup so malformed envelopes retain file-error codes and paths. Keep deferred SQL instruction HTTP errors and their metadata intact, map tagged storage HTTP and local policy failures to the established staging error type, and preserve portable file-error codes when the host does not recognize a native errno.
Both requested paths and resolved targets must lie within configured allowed roots. Symlinks between authorized roots remain supported; escaped targets are rejected, stricter than the Thrift handler’s lexical path checks.
Dependencies
Builds select databricks/databricks-sql-kernel#465 at d9fcf834d36dc7f3de1621225db716200151fa0f. Merge and release require compatible platform versions, updated dependency pins/locks, and clean installed-package validation. Published native 1.4.0 lacks completion APIs.
Tests and validation
525 focused kernel/session tests, TypeScript build, lint and formatting checks pass. Retained source-built sync/async staging comparisons at kernel
029c59ccmatch Thrift on DBSQL CURRENT: two matching workflows and zero differences, with initial and changed bytes, removal and owned cleanup verified. The comparison verified its loaded native library and retains that source/build identity. Retained performance evidence keeps its recorded build qualification. Clean installed-package and scheduled activation remain open.